#ifndef IMAGE_LOADER_H
#define IMAGE_LOADER_H

#include <stdbool.h>
#include <stdint.h>
#include "../../common/queue/user_queue.h"

/**
 * @brief 初始化图像加载器
 *
 * @param path 图像文件所在的目录路径
 * @param frame_width 图像帧的宽度（像素）
 * @param frame_height 图像帧的高度（像素）
 * @param buffer_size 缓冲区中允许存储的最大帧数
 * @return true 初始化成功
 * @return false 初始化失败
 *
 * @note 必须在调用其他图像加载器函数之前调用此函数。
 */
bool image_loader_init(const char *path, int frame_width, int frame_height, int buffer_size);

/**
 * @brief 获取文件夹中的总帧数
 *
 * @return int 文件夹中图像帧的总数
 *
 * @note 此函数依赖于 `image_loader_init` 的初始化结果。
 */
int image_loader_get_frame_count(void);

/**
 * @brief 加载帧到指定缓冲区
 *
 * @param buffer 指向目标缓冲区的指针
 * @param start_frame 起始帧的索引
 * @return true 加载成功
 * @return false 加载失败
 *
 * @note 此函数会从 `start_frame` 开始加载 `buffer_size` 个帧到缓冲区。
 *       如果 `start_frame + buffer_size` 超过总帧数，则会从头开始循环加载。
 *       文件格式需要是000.bin, 099.bin这种格式
 */
bool image_loader_load_frames(Queue_t *buffer, int start_frame);

/**
 * @brief 获取一个帧数据，并释放上一帧的内存
 *
 * @param buffer 指向目标缓冲区的指针
 * @return void* 指向当前帧数据的指针
 *
 * @note 此函数会自动释放上一帧的内存，调用者无需手动管理。
 *       如果缓冲区为空或获取失败，返回 NULL。
 */
void *image_loader_get_frame_data(Queue_t *buffer);

/**
 * @brief 释放图像加载器的资源
 *
 * @note 此函数会清理图像加载器的内部状态。
 *       在程序结束或不再需要图像加载功能时调用。
 */
void image_loader_deinit(void);

#endif // IMAGE_LOADER_H
